<?php
/***************************************************************************
                                  Class1.php
                              -------------------
  
       A PHP5 class used as a reference for Mdoc class usage and test. 

 **************************************************************************/
 
// The class file can start with some code and comments which are just ignored by Mdoc parsing
//if (realpath($_SERVER['SCRIPT_FILENAME']) == __FILE__) die("FILE ACCESS METHOD NOT ALLOWED");

// Declare undocumented parent and interface classes (ignored by Mdoc), useful to check
// this file is parsed correctly by the PHP interpreter
abstract class Parent1 { };
interface Interface1 { };
interface Interface2 { };

/**
 * Syntactically correct PHP5 class example.
 *
 * Every code documenting block, like this one, has the same format;  
 * the very first line is the "short description", following lines up 
 * to first @info is the "long description". Every @info comment starts 
 * a line with @ (more precisely \n * @ sequence); they are also called
 * active comments (sometimes written @ctive comments).
 *
 * The long description is optional.
 *
 * The long description can have some "display" formating block, such 
 * as the [example] one or the [code] one.
 *
 * For PHP interpreter, the default scope is "public" (so @private 
 * and @protected should not be forgotten in PHP4 classes).
 *
 * @version   1.0
 * @date      28 Aug 2005
 */
class Class1 extends Parent1 implements Interface1, Interface2 {

/**
 * A "member" constant.
 *
 * As of PHP5, constant can be declared in a class, with the new "const"
 * statement and is accessed with class member syntax even within the class
 * itself. Their scope is global assuming to use class member syntax.
 *
 * [code]
 * // A class constant is accessed with class member syntax
 * class Test {
 *
 *   const HELLO = "Hello world!";
 *
 *   function __construct() {
 *     echo Test::HELLO;  // even within the class
 *   }
 * }
 * // Accessing the class constant in global scope
 * echo Test::HELLO;
 *
 * @type int
 */
const START = 0;  // this comment isn't considered for documenting

/**
 * New line chars.
 *
 * This chars are celared in a group of constants, so their inline
 * comments in code are considered for documenting.
 */
const NL_DOS = "\r\n";  // for Windows environment
const NL_MAC = "\r";    // for Mac environment
const NL_NIX = "\n";    // for Unix/Linux environment

/**
 * Integer property.
 *
 * A private integer property set to 27.
 */
private static $anint = 27;

/**
 * Protected and static integer property.
 *
 * This property has an initial value.
 *
 * @type int
 */
protected static $apsint = 0;

/**
 * Mixed property.
 *
 * The "type" comment is required so if 
 * property type isn't sure, use "mixed".
 *
 * @type mixed
 */
public $mixer;

/**
 * Private property.
 *
 * @type object
 */
private $privob;

/**
 * Protected property.
 *
 * @type object
 */
protected $protob;

/** 
 * Stack of XHTML formated output string.
 *
 * This property has a "multiline" initial value.
 *
 * @type array
 */
public static $multi = array(
                         'next' => "<hr class=\"next\" />",
                         'nl' => "<br />",
                         'trap' => "<b>a ; to trap value parsing</b>",
                       );

/**
 * Constructor with PHP5 class syntax.
 *
 * Print an instance creation message.
 * 
 * @public
 * @return (object) an instance of this class (@return comment 
 *                  is mandatory for any member function)
 */
function __construct() {

  echo "A new instance has been created.";
}

/**
 * A method with 3 parameters.
 *
 * @param (string) $p1 the first parameter
 * @param (int) $p2 the second parameter
 * @param (string) $p3 the 3rd parameter
 * @return (void)
 */
protected function m3param($p1, int $p2, string $p3) {

  // Print the 3 parameters
  echo $p1 . "\n";
  echo $p2 . "\n";
  echo $p3 . "\n";

  return true;
}

/**
 * A method with parameters passed by reference.
 *
 * The function statement presents the & reference char in
 * different places (& $p1 and &$p2).
 *
 * @warning  unstable
 * @param (string) $p1 the 1st parameter
 * @param (bool) $p2 the 2nd parameter
 *                   has a two-line comment
 * @return (string) the function result
 */
private function mpbyref(& $p1, bool &$p2) {

  return $p1;
}

/**
 * A method with no parameter.
 *
 * @return (void)
 */
final private function mnop() {

  print get_class_name($this);
}

/**
 * A method with significant documenting comments.
 *
 * Unordered list is a sequence of lines starting all with same -+* bullet,
 * indented on same column at least 2 spaces from margin star, so
 *
 *     - list item 1
 *       on two lines
 *     - second item
 *     - another list item
 *            + sublist it1
 *            + sublist it2
 *                 * subsub A
 *                 * subsub B
 *                 * subsub C
 *     - another ?
 *       again!
 *
 * is translate into an HTML unordered list <ul></ul> (max 8 items by list, 
 * nested up to 4 levels)
 *
 * @warning  unstable
 * @param (int) $p1 the first parameter
 * @param (mixed) $p2 the title of text (string)
 *                    or false (bool) to get all
 * @param (string) $p3 the third parameter
 *                  is commented onto
 *                  several lines
 *                  - list item A
 *                  - list item B
 * @param (array) $p4 the address structured list:
 *                    'name' => a name
 *                    'address' => an address
 *                    'city' => a city name
 * @return (void) if echo flag $p1 is true
 *                a line of comment to test parsing
 *         (string) the printable solution if echo flag is false (default)
 */
public function mlotdoc($p1, $p2 = "a string", $p3 = "another string", $p4 = array()) {

  if ($p1) {
    return;
  } else {
    return "whatever";
  }
}

/**
 * Very simple method with PHP4 style.
 *
 * This method is declared like it would be in a PHP4 class.
 *
 * @return (void) 
 */
function hello() {

  echo "Hello world!";
}
}
?>
